Anatomy & Folder Structure
Supacharger uses four ownership classes. The colours below are labels as well as visual cues, so the tree remains understandable without colour.
application/├── .agents/│ ├── skills/Core exactSupplied agent skills│ └── …Developer ownedProduct instructions and skills├── .supacharger/│ ├── managed-files.jsonCore exactExecutable ownership manifest│ ├── core-lock.jsonDeveloper ownedInstalled immutable Core reference│ ├── migration-aliases.jsonDeveloper ownedReviewed ledger mappings│ └── backups/Developer ownedUpdate recovery copies├── docs/│ └── bruno/supacharger-rpc/Core exactCanonical reusable RPC requests├── messages/Developer ownedEnglish source and translations├── public/Developer ownedURL-addressable product assets only├── scripts/│ └── check-bruno-rpc-parity.mjsCore exact├── src/│ ├── app/│ │ ├── (supacharger)/Core exactReusable App Router pages and handlers│ │ │ ├── (unauthenticated)/Core exactLogin, signup, reset and Auth callbacks│ │ │ ├── (verified)/Core exactMFA and verified-only recovery│ │ │ ├── (onboarded)/Core exactBilling acquisition boundary│ │ │ ├── (authenticated)/Core exactAccount and organisation settings│ │ │ └── api/Core exactValidated managed Route Handlers│ │ ├── (project)/Developer ownedProduct, marketing and extension routes│ │ └── layout.tsxDeveloper ownedFonts and application provider composition│ ├── assets/svgr/ui/Developer ownedBrand-customisable inline loaders│ ├── components/│ │ ├── sc_demo/Developer ownedReplaceable examples│ │ └── ui/Developer ownedProduct UI primitives; not imported by managed forms│ ├── i18n/Developer ownedLocale policy and catalogue loading│ ├── lib/supabase/│ │ ├── supacharger/Core exactShared SSR and Auth implementation│ │ └── types.tsMerge managedGenerated database types│ ├── styles/│ │ ├── project.cssDeveloper ownedProduct theme and global rules│ │ ├── supacharger-auth.cssDeveloper ownedAuth semantic presentation│ │ ├── supacharger-account.cssDeveloper ownedAccount semantic presentation│ │ └── supacharger-organisations.cssDeveloper ownedOrganisation presentation│ ├── supacharger/Core exactReusable behaviour, semantic components and contracts│ │ ├── account/Core exact│ │ ├── auth/Core exact│ │ ├── billing/Core exact│ │ ├── components/primitives/Core exactPresentation-neutral managed controls│ │ ├── organisations/Core exact│ │ ├── styles/Core exactTailwind entry and accessibility invariants│ │ └── supacharger-config-contract.tsCore exact│ ├── supacharger.adapters/Developer ownedAuth, account and organisation extensions│ ├── supacharger.config.tsDeveloper ownedTyped product feature policy│ └── proxy.tsCore exactOne-verification session boundary├── supabase/│ ├── config.tomlMerge managedLocal Supabase and Auth Hook configuration│ ├── functions/│ │ ├── process-image-upload/Core exact│ │ └── _shared/│ │ ├── image-target-contract.tsCore exact│ │ ├── image-transform.tsCore exact│ │ └── image-targets.tsDeveloper ownedProduct resize policy│ ├── migrations/Forward onlyPermanent per-project database ledger│ └── templates/Developer ownedEmail and claims extension examples├── test/│ ├── shared contract testsCore exact│ └── project-* testsDeveloper ownedProduct schema and behaviour├── components.jsonCore exact├── package.json / package-lock.jsonMerge managed├── postcss.config.mjsCore exact├── tailwind.config.tsMerge managed└── tsconfig.jsonCore exactReading the tree
Core exact paths are copied from the immutable Core lock and must be byte-identical. Merge managed files have a shared contract but retain application values and dependencies. Forward only paths are permanent histories: add new migrations, never replace an installed one. Developer owned files survive every Core update.
src/supacharger.config.ts supplies application values and is checked against the exact SupachargerConfig type. Managed forms render stable semantic sc-* classes; their dimensions, colours, radii, typography, spacing and layout live in the developer-owned stylesheets under src/styles/.
The CLI reads .supacharger/managed-files.json, previews each ownership action, preserves developer paths, runs the declared checks and advances .supacharger/core-lock.json only after the exact contract passes.
Naming
Use lowercase kebab-case for files and folders, PascalCase for React component names, and route groups such as (supacharger) and (project) to separate ownership without changing public URLs.